Openclaw 설치 트러블 슈팅

🦞 OpenClaw 설치 및 트러블슈팅 리포트

사용자 환경: MacBook Air (M2, 2026), macOS, Node.js 22

작업 일자: 2026년 3월 4일

1. 초기 설치 및 모델 설정 이슈

  • 상황: OpenClaw 설치 후 구동 시 API rate limit reached 에러 발생.
  • 원인: google/gemini-3-pro-preview 모델의 무료 티어 할당량 제한으로 인해 첫 인사가 실패함.
  • 해결: * 설정 파일(~/.openclaw/openclaw.json)에서 모델을 더 가볍고 제한이 적은 google/gemini-3-flash 또는 gemini-1.5-flash로 변경 권장.
  • 터미널 기반 설정 변경 도구(openclaw config set) 활용법 숙지.

2. 텔레그램 채널 연동 이슈

  • 상황 1: Unrecognized key: "providers" 에러 발생.

  • 원인: 버전 업데이트로 인해 설정 경로가 providers에서 channels로 변경됨.

  • 해결: openclaw config set channels.telegram.botToken 명령어로 경로 수정.

  • 상황 2: token 키 인식 불가.

  • 원인: 정확한 키 이름이 token이 아닌 botToken임이 확인됨.

  • 해결: openclaw config get channels.telegram을 통해 유효한 키 목록 확인 후 botToken으로 재설정.

  • 상황 3: 메시지 무시(Dropped) 경고.

  • 원인: groupPolicy가 allowlist로 설정되어 있으나 허용 목록이 비어 있음.

  • 해결: groupPolicy를 "open"으로 변경하여 모든 수신 메시지 허용 처리.

3. 게이트웨이 인증 및 서비스 이슈

  • 상황 1: unauthorized: gateway token mismatch 에러 발생.

  • 원인: 백그라운드 서비스(Gateway)와 터미널 클라이언트(CLI) 사이의 인증 토큰이 서로 다름.

  • 해결: gateway.auth.token과 gateway.remote.token을 동일한 문자열로 일치시킴.

  • 상황 2: Service: LaunchAgent (not loaded) 및 RPC probe: failed.

  • 원인: 맥북 시스템 서비스로 OpenClaw가 등록되지 않아 게이트웨이가 정상 구동되지 않음.

  • 해결: 1. openclaw gateway install로 서비스 등록.

  1. openclaw gateway start로 서비스 실행.
  2. openclaw gateway status를 통해 RPC probe: ok 상태 확인 완료.

4. 보안 권고 사항 (Action Required)

  • 내용: 작업 과정 중 텔레그램 봇 토큰이 터미널 로그를 통해 노출됨.
  • 조치: 텔레그램 @BotFather를 통해 기존 토큰을 **Revoke(폐기)**하고 새 토큰을 발급받아 channels.telegram.botToken에 재등록 필요.

✅ 최종 상태 요약

  • Gateway Status: Running (Active)
  • RPC Probe: OK (Success)
  • Telegram Channel: Configured (botToken set, groupPolicy open)
  • Core Skills: session-memory, command-logger, boot-md 활성화 완료

Tip: 향후 설정 변경이 필요할 때는 openclaw config get 명령어로 현재 구조를 먼저 파악한 뒤 set 명령어를 사용하면 에러를 줄일 수 있습니다.